IBM Books

Access Integration Services Using and Configuring Features Version 3.3


Using Web Server Cache

This chapter describes the 2212 Web Server Cache feature. It contains the following:


Web Server Cache Overview

Web Server Caching is only available for 2212 models with the High Performance System Card. You can upgrade 2212 models without the High Performance System Card. Contact your IBM representative for more information.

Web Server Caching stores frequently requested web pages for quick retrieval. Web Server Caching keeps frequently requested items closer to the clients; this frees up server resources currently being used for file serving and communication connections. The 2212 Web Server Cache provides high-speed access to web pages while reducing host communications overhead. The 2212 Web Server Cache:

All 2212 network interfaces that support TCP/IP connectivity, support connectivity between Web Server Cache, HTTP servers, and clients.

Figure 10 shows how Network Dispatcher works without Web Server Caching.

Figure 10. Network Dispatcher without Web Server Cache

NetWork Dispatcher without Web Server Cache

  1. Request comes for cluster address

  2. Network Dispatcher forwards a request to servers

  3. Server sends response back to client.

Figure 11 shows how Network Dispatcher works with Web Server Caching and the requested page is not currently cached. Web Server Caching loads the response into the cache if the policies allow it.

See "Using the HTTP Proxy" for information about HTTP Proxy.

A partition is a division of the cache core memory. Each cache partition is partitioned independently and allows the device to support multiple clusters.

Figure 11. Network Dispatcher with Web Server Cache and No Cache Hit

Network Dispatcher with Web Server Cache and No Cache Hit

  1. Request comes for cluster address

  2. Network Dispatcher forwards the request to HTTP Proxy if active

  3. HTTP Proxy looks in the cache partition

  4. HTTP Proxy does not find the requested page in the cache partition

  5. HTTP Proxy gets server information from Network Dispatcher if required for new connection

  6. HTTP Proxy forwards the request to the server. (For the TCP connection the source IP address is the address of the 2212 network interface. The destination IP address is the server interface IP address.)

  7. Server sends response back to HTTP Proxy

  8. HTTP Proxy sends the response to client

  9. HTTP Proxy loads the response into cache partition if the policies allow it.

Figure 12 shows how Network Dispatcher works with Web Server Caching when the requested page is currently cached.

Figure 12. Network Dispatcher with Web Server Cache and Cache Hit

NetWork Dispatcher with Web Cache

  1. Request comes for cluster address

  2. Network Dispatcher forwards request to HTTP Proxy

  3. HTTP Proxy looks in the cache partition

  4. HTTP Proxy finds the requested page in the cache partition

  5. HTTP Proxy returns response to the client.

Caching

The 2212 Web Server Cache has:

Caching of web pages
The 2212 can cache objects that are requested from the server. This caching is called transparent caching. You can use talk 6 to enable or disable transparent caching for a partition.

The alternative to transparent (automatic) caching is manual caching. In this case, an external agent uses the cache manager to cache a web page. For information about external web caching see External Cache Control Manager Overview.

Stale cached objects are automatically deleted. The 2212 Web Server Cache supports both HTTP 1.0 and 1.1 servers and clients.

Flexible cache policies
Allows users to specify whether certain broad classes of web objects (images, non-image-static pages, dynamic pages) are to be cached. You can also specify maximum sizes for objects and cache partitions. In addition, users may specify URL masks to explicitly include or exclude classes of web objects as appropriate to their environment.

Flow chart for transparent caching policies:

  1. Is caching enabled and transparent caching enabled?

    • No - The object is not cached.

    • Yes - Continue with the next check.

  2. Is the object size within the maximum object size?

    • No - The object is not cached.

    • Yes - Continue with the next check.

  3. Has the object expired?

    • No - Continue with the next check.

    • Yes - The object is not cached.

  4. Are HTTP headers to be used, and was one of the HTTP headers used?
    Note:The HTTP header used is a Cache-Control header with either the DO or DONT directives.

    1. No - HTTP headers are not to be used or there is no header on the object?

      1. Is the URL excluded by an exclude mask?

        • Yes - The object is not cached.

        • No - Continue with the next check.

      2. Is the URL included via an include mask?

        • Yes - Go to step 5.

        • No - Continue with the next check.

      3. Is this a dynamic object?

        • No - Continue with the next check.

        • Yes - The object is dynamic.

          1. Are dynamic objects cachable?

          -- Yes - Continue with the next check.

          -- No - The object is not cached.

      4. Is the object an image (.jpg or .gif)?

        • No - Continue with the next check.

        • Yes - The object is an image.

          1. Are images cachable?

          -- Yes - Continue with the next check.

          -- No - The object is not cached.

      5. Is the object a static non-image?

        • No - Continue with the next check.

        • Yes - The object is a static non-image file.

          1. Are static non-images cachable?

          -- Yes - Continue with the next check.

          -- No - The object is not cached.

    2. Yes - Are HTTP headers used, and does the object include a cache control header?

      1. Do the HTTP headers indicate "DO" cache?

        1. No - The object is not cached.

        2. Yes - Continue with the next check.

  5. Is there room in the partition for the object?
    Note:The least recently used objects will be removed in order to try to make room for the object.

    • No - The object not cached.

    • Yes - The object is cashed.

Support of multiple independent caches
Supports up to 16 partitions, allowing a single 2212 to provide independent cache services for multiple clusters. Cache partitions are fully independent. Each cache partition maintains its own contents and policies.

Full TCP/IP server connectivity
Communicates with both servers and clients across all 2212 network interfaces which support the TCP/IP protocol suite.

Load balancing to back-end servers (by way of Network Dispatcher)
Uses Network Dispatcher to define groups of servers and balance load between servers to speed lookup of web pages not found in the cache.

Backup cache support
Allows users to define a second 2212 as a backup server cache. The backup server cache can operate as a "cold" backup using the Network Dispatcher High Availability function, See High Availability for Network Dispatcher for more information.
Note:The backup server cache comes up empty. You must repopulate the backup server cache by using either transparent caching (For example: requests for URLs) or by using the external cache control manager function to force pages into the cache.

Using the HTTP Proxy

There can be more than one HTTP Proxy in the 2212. Each one represents a cluster address/port that is doing caching. There can be multiple HTTP proxies that uses a cache partition.

The HTTP Proxy handles receiving requests from clients and tries to satisfy them from its cache partition. If the HTTP Proxy can satisfy the request, it responds back to the client. If the HTTP Proxy cannot satisfy the request, it opens a TCP connection with a server in an attempt to satisfy the request. When the server responds to the HTTP Proxy's request, the HTTP forwards the server's response to the client. The HTTP Proxy also sees if the response from the client should be cached. If the response should be cached, the HTTP Proxy passes it to the cache partition.

HTTP Proxy handles connections using the following guidelines.


Scaleable High Availability Cache

Scaleable High Availability Cache allows a group of connected Web Server Caches to function as one large cache. The maximum number of caches in a group is sixteen. A failure with one cache member reduces the total amount of memory available for caching, rather than end all cache functions. See Figure 9 for a configuration example.

The individual caches make up the total cache space. If a cache becomes nonfunctional, incoming pages will continue to be cached by the remaining working caches.

Incoming web pages are stored in the group's caches. They are distributed evenly among the available caches. Each cache in the group maintains a table that tracks the number of reachable caches in the group and their IP addresses. The tables are identical for all caches in a group. The tables are used along with a Cache Array Routine Protocol (CARP) algorithm to determine which cache owns a particular URL. The information for the table comes from the Network Dispatcher device and indirectly from the caches that are using the HTTP advisor to keep track of the status of the Web Server Caches in the group. The following figures demonstrate the conditions for locating a URL using SHAC.

Figure 13 shows the request from Network Dispatcher found in the first cache that received the request.

Figure 13. Cache Request Found

Cache Request Found

  1. An HTTP request for a web page comes from a client to the Network Dispatcher.

  2. The request is forwarded by the Network Dispatcher to one of the Web Server Caches. The cache receives the request and finds that it contains the web page.

  3. The cache sends the web page directly to the client by bypassing Network Dispatcher.

Figure 14 shows a request not found in the first cache that received the request from Network Dispatcher and the CARP algorithm indicates that another cache owns the URL.

Figure 14. Request Forwarded to the Responsible Cache

Request Forwarded to the Responsible Cache

  1. An HTTP request for a web page comes from a client to the Network Dispatcher.

  2. The request is forwarded by the Network Dispatcher to one of the Web Server Caches.

  3. The cache receives the request and does not find the web page in its cache. The cache then uses an algorithm to locate the cache responsible for the web page.

  4. The request is then forwarded to the cache responsible for that web page.

  5. The cache responsible for the web page receives the request, finds the web page and sends the web page to the client.

Figure 15 shows a request not found in the cache that received the request from Network Dispatcher, but the CARP algorithm indicates that the cache is responsible for the URL.

Figure 15. Request Forwarded to Backend Server

Cache Request Forwarded to Backend Server

  1. An HTTP request for a web page comes from a client to the Network Dispatcher.

  2. The request is forwarded by the Network Dispatcher to one of the Web Server Caches.

  3. The cache receives the request and does not find the web page in its cache. The cache uses an algorithm to determine that it is responsible for the web page.

  4. The cache sends the request to the backend server.

  5. The backend server finds the web page; that web page is returned through the cache that is responsible for that web page to the client. It will be cached if the cache has been configured to cache that page. See Configuring and Monitoring Web Server Cache for configuration information.

Figure 16 shows a request that is not found in any cache in the cache group.

Figure 16. Request Forwarded to the Responsible Cache and Not Found

Cache Request Forwarded to the Responsible Cache and Not Found

  1. An HTTP request for a web page comes from a client to the Network Dispatcher.

  2. The request is forwarded by the Network Dispatcher to one of the Web Server Caches.

  3. The cache receives the request and does not find the web page in its cache. The cache then uses an algorithm to locate the cache responsible for the web page. The request is then forwarded to the cache responsible for that web page.

  4. The cache responsible for the web page receives the request and does not find the web page.

  5. The cache responsible for the web page sends the request to the backend server pool.

  6. The backend server finds the web page; that web page is returned through the cache that is responsible for that web page to the client. It will be cached if the cache has been configured to cache that page. See Configuring and Monitoring Web Server Cache for configuration information.

External Cache Control Manager Overview

The External Cache Control Manager allows Web Servers the ability to control the Web Server Cache and the Host On-Demand Client Cache. This control is by way of a user-defined port for the External Cache Control Manager (ECCM). The ECCM accepts connections and processes commands targeted for a partition over this port. The commands use the External Cache Control Protocol (ECCP). The ECCP uses vector/subvector formats to send request commands and response commands.

One command vector can request multiple functions by having multiple subvectors. Each subvector represents a new function. The command vector indicates to which cache partition the commands are applied by specifying the cluster address and the port of a proxy defined on that partition.

The following functions are supported by ECCP:

Dependency Table

The External Cache Control Manager allows you to create a dependency table for each cache partition. This table is particularly useful when dealing with dynamic objects in the cache.
Note:Caching dynamic objects requires that the objects be updated when the information from which these objects were created changes.

The information to build the dependency table must be passed to the cache partition using the External Cache Control Manager interface.

The dependency table gives you the ability to assign a dependency string to a URL object (cached web page). These dependencies are stored in dependency tables in the Web Server Cache by using the External Cache Control Manager interface. The dependency table is used to invalidate objects in the cache partition that have this dependency when the source for the object changes. Without a dependency table, you would have to send a separate delete command for each object to be deleted.

Example: The following three databases contain various objects.

                database1            database2            database3
                ---------            ---------            ---------
                object_a             object_a             object_b
                object_b             object_c             object_e
                object_c             object_d  

Assume that all the pages object_a through object_e are in the cache. If database2 changes, you can send (via Cache Control Manager interface) an invalid dependency database2 command. The Web Server Cache will then delete object_a, object_c, and object_d from the cache partition.
Note:An object does not need to be in the cache partition to be in the dependency table.

External Cache Control Manager Authentication

The External Cache Control Manager allows you to control user access. This is accomplished by requiring incoming connections to have a userid and password. The userid and password are tied to the logon userid and password. If the device is password protected and the incoming connection does not have a userid and password or the userid and password are not valid, an authentication error response is returned and the connection is closed. If the userid and password are valid, the user may send commands over that interface.

Security

Security provides a way to authenticate the ECCP user. Four types of authentication can be configured (RADIUS, TACACS, local, or none). Data encryption is not provided. Each authentication mechanism (except for none) requires both a user ID and associated password. This information is passed to the 2216 using the authentication vectors. The user ID can range from 1-8 bytes, while the password can range from 1-8 bytes. The password passed on the External Cache Control connection must be encrypted using DES encryption. The random 8 byte seed used for the encryption is also passed. The key for the encryption will not be passed over the connection. See "Modify" for information about setting the port and TCP values.
Note:The Authentication vector will be ignored if the router is not password protected.

External Cache Control Protocol

The External Cache Control Protocol (ECCP) gives the back-end servers the ability to control the router cache. This control maximizes cache performance.

The ECCP is an architected protocol interface that allows the servers to add and delete objects as well as modify the cache policies.

The external cache control manager is defined in the router (Web Server Cache or Host On-Demand Client Cache) to accept connections and process commands targeted for a cache partition.

Configuration

The external cache control manager is configured with the following parameters:

User-defined port:
The port number where the external cache control manager listens and accepts connections. If 0 is configured, the external cache manager is assumed to be disabled.

Valid Values: 0 to 65535

Default Value: 0

Maximum TCP timeout value:

Valid Values: 5 to 240 seconds

Default Value: 120

Encryption Key:
The Encryption Key will be used if the box is password protected. The Encryption Key must be 16 hex characters (0-9,a-f,A-F).

External Cache Control Manager Function Descriptions

This section describes the functions of the External Cache Control Manager.

Adding an Object

An HTTP response object can be added to the cache partition. The format of the object data must be the same as an HTTP response. The External Cache Control Manager will parse the headers of the response and pull out the information that is needed. Then the object is added to the cache.

The difference between the Add Object and the Add (Force) Object is that the Add (Force) Object will ignore any Cache_Control headers specifying DO or DONT. All other headers that the HTTP Proxy use to determine whether to cache an object are still used. For both Add Object and Add (Force) Object the object will be replaced in the cache partition regardless of the date.

Deleting an Object

An HTTP object can be deleted from the cache. The URL for the object is given.

Using the Dependency Table

The dependency table for a cache partition can be modified, listed, and used to invalidate objects.

When modifying the dependency table (adding or removing dependencies), both the dependency and the dependency URL must be given. In addition, there are two other ways to modify the dependency table. One is to reset the entire table, an entire dependency (i.e. remove the dependency completely), or a URL dependency (i.e. remove the URL dependency from all dependencies). The other is to do a garbage collect on the dependency table. The garbage collect cleans up all the dependency URLs from the dependency table that do not have an object with that URL in the cache.

There are multiple ways of listing the information in the dependency table. The entire table can be retrieved, all the dependency URLs for a given dependency can be retrieved, or all the dependencies that have a give dependency URL can be retrieved.

Objects can be removed (invalidated) from the cache using the Dependency Table. Using the dependency, the Dependency Table is checked. Any dependency URL for that dependency will be removed from the cache partition.

Disabling/Enabling a Partition

This function allows the cache partition state to be changed. In order to use the External Cache Control Manager the cache partition must be in the correct state. The cache partition must be disabled in order to purge all the objects from it.

Using Policies

The policies for a partition can be listed or modified. Each policy can be done separately or as a group. When modifying a policy, the correct type of data must be passed for that policy. See External Cache Control Protocol (ECCP) Vector Formats (Policy Command Subvector and Policy Response Subvector) for the format of the data based on the policy.

Purging the Partition

This function allows all the objects in the cache partition to be removed. The cache partition must be in the disabled state in order to purge it.

Querying an Object

This function gives the ability to see if an object is in the cache partition. In addition, if the object is in the cache partition and has a last modified date, that date is returned. See "External Cache Control Protocol (ECCP) Vector Formats" (Query Response Subvector) for the format of the date returned.

Using Statistics

This function gives the ability to list and reset (clear) the cache partition statistics. See "External Cache Control Protocol (ECCP) Vector Formats" (Statistics Response Subvector) for the format of the statistics.

Using a URL Mask

This function gives the ability to list and modify the URL masks for a cache partition. The URL type include, exclude, dynamic, or Host On-Demand Client Cache applet must be given when using this function. You must list one URL type. This function does not work with multiple URL types.

You have the ability to add a URL mask. If the URL mask is an include, dynamic, or Host On-Demand Client Cache applet mask the lifetime needs to be given. Adding a dynamic mask will modify the current dynamic URL mask and adding a Host On-Demand Client Cache applet mask will modify the current Host On-Demand Client Cache applet mask. You have the ability to delete a URL mask. This function is not valid for the dynamic URL mask or the Host On-Demand Client Cache applet mask. You have the ability to reset all the URL masks of a peculiar type. Resetting the dynamic URL mask resets to the default dynamic URL mask and resetting the Host On-Demand Client Cache applet mask resets to the default Host On-Demand Client Cache applet mask.
Note:The dynamic mask is used with Web Server Cache images and the Host On-Demand Client Cache applet mask is used with images that have the Host On-Demand Client Cache feature.

External Cache Control Protocol (ECCP) Vector Formats

The ECCP clients sends commands and receives responses using a vector format. The authentication vector is required if the box is password protected. If the box is not password protected the authentication vector is ignored when received.

Vector Formats

This section describes the field descriptions for the Vectors.

Figure 17. Command Response Vector

Command Response Vector

Length: The unsigned 32-bit value representing the length (in bytes) of the entire vector, including the length and key fields, as well as any subvectors and subfields. The acceptable range is 22-4GB for command vectors , and 38-52 for authentication vectors.

Key: The unsigned 16-bit value representing the major vector key. The major vector keys are:

Cluster IP: The IP address of the cache cluster associated with the target cache partition.

Port: The Port number of the cache cluster associated with the cache partition.

Correlator: The unsigned 32-bit value used by ECCP client to associate the command response to the command request.

Retcode: The unsigned 32-bit value representing the return code. This is only present in the response vectors.

Vectors contain one or more subvectors. The authentication request vector requires both the name and the password subfields. The command request vector contains one or more command subvectors. If multiple subvectors are present in the command request vector, then multiple subvectors will be present in the command response vector. If a severe error occurs, it is reflected in the Retcode field of the command response vector.

Authentication Request Vector

The Authentication Request Vector must be the first vector on the External Cache Control Connection if the box is password protected. If the box is not password protected this vector will be ignored.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x4A00

6-15
Reserved

Reserved for future use.

16-n
Name Subfield.

n+1-m
Password Subfield.

Command Request Vector

The Command Request Vector sends commands to the External Cache Control Manager. If the box is password protected a valid Authentication Request Vector must first be received by the External Cache Control Manager before the commands are accepted.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x4B00

6-9
Cluster IP Address

The IP address of a cache cluster (HTTP Proxy) associated with the target cache partition.

10-11
Port

The port number of the cache cluster (HTTP Proxy) associated with the target cache partition.

12-15
Correlator

The correlator is used to associate the command responses to its matching command request.

16-n
Subvectors

One or more of the following subvectors may be appended.

Authentication Response Vector

The Authentication Response Vector is returned in response to an Authentication Request Vector.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x4A01

6-15
Reserved

Reserved for future use.

16-19
Return Code

This is the return code for the vector. See "Return Codes".

20-n
Subvectors

There are currently no vectors on the Authentication Response Vector.

Command Response Vector

The Command Response Vector is returned in response to a Command Request Vector.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x4B01

6-9
Cluster IP Address

The Cluster IP Address of a cache cluster (HTTP Proxy) associated with the target cache partition.

10-11
Port

The port number of the cache cluster (HTTP Proxy) associated with the target cache partition.

12-15
Correlator

The correlator is used to associate the command responses to its matching command request.

16-19
Return Code

This is the return code for the vector. See "Return Codes".

20-n
Subvectors

Zero or more of the following subvectors may be appended.

Subvector Formats

This section describes the subvector formats. Subvectors follow the same basic format as the major vector:

Figure 18. Subvector Format

Subvector Format

Length: The unsigned 32-bit value representing the length (in bytes) of the entire subvector, including the length and key fields as well as any subfields. The acceptable range is 6-4GB (we are not checking the upper bound)

Key: The unsigned 16-bit value representing the subvector key. The request subvector keys include:

The response subvector keys returned are:

Retcode: The unsigned 32-bit value representing the return code for the request subvector. This is only present in the response subvector.

Add Object Command Subvector 

The Add Object Command Subvector is used to add a Web Object to the cache partition.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0110

6-n
URL Subfield

n+1-m
Object Subfield

Add (force) Object Command Subvector 

The Add (force) Object Command Subvector is used to add a Web Object to the cache partition. It differs from the Add Object Command Subvector in that any Cache Control headers of the object are ignored.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0100

6-n
URL Subfield

n+1-m
Object Subfield

Delete Object Command Subvector 

The Delete Object Command Subvector is used to remove a Web Object from the cache partition.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0400

6-n
URL Subfield

Dependency Command Subvector 

The Dependency Command Subvector is used to modify/list the Dependency Table or invalidate objects using the Dependency Table.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0A00

6-7
Command

The dependency Command to be performed.

0x0001
Get the dependency table (see Dependency type for the dependency)

0x0002
Add a new dependency/dependency URL to the Dependency Table

0x0003
Remove a dependency/dependency URL from the Dependency Table

0x0004
Reset the dependency table information (see Dependency type for the dependency)

0x0005
Invalid an Object based on a dependency

0x0006
Garbage collect the Dependency Table

8-9
Dependency Type

The dependency type field is used to identify data to be changed. This data is then changed using the Dependency Command.

0x0000
No dependency type

0x0001
Use the command on the entire table.

  • If the command above is 0x0001 (Get) - get the entire table.

  • If the command above is 0x0004 (Reset) - clear the entire table.

0x0002
Use the Command on a dependency basis.

  • If the command above is 0x0001 (Get) - get all the URLs for the given dependency.

  • If the command above is 0x0004 (Reset) - clears a dependency from the table.

0x0003
Use the Command on a URL basis

  • If the command above is 0x0001 (Get) - get all the dependency for the given dependency URL.

  • If the command above is 0x0004 (Reset) - clears a dependency URL from the table.

10-n
Zero or more subfields.
Dependency Subfield
Note: This subfield must be first when both subfields are required.
         Required when have these Command-Dependency Type.
 
   Command           Dependency Type
    0x0001               0x0002
    0x0002               0x0000
    0x0003               0x0000
    0x0004               0x0002
    0x0005               0x0000
 
URL Subfield
Note: This subfield must be second when both subfields are required.  
         Required when have these Command-Dependency Type.
 
  Command            Dependency Type
   0x0001                0x0003
   0x0002                0x0000
   0x0003                0x0000
   0x0004                0x0003
 

Disable Command Subvector 

The Disable Command Subvector is used to disable a Cache Partition.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0300

Enable Command Subvector 

The Enable Command Subvector is used to enable a Cache Partition.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0200

Policy Command Subvector 

The Policy Command Subvector allows you to modify a cache partition or list the information in a cache partition.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0500

6-7
Command

The command to be performed.

0x0001
Get the policy

0x0002
Update a policy

8-9
Policy Type

The Policy Type is used to identify data to be changed. This data is then changed using the Policy Command.

0x0001
Transparent caching

0x0002
HTTP Cache Control Header

0x0003
Cache dynamic objects

0x0004
Cache image objects ("*.gif," "*.jpg")

0x0005
Cache static objects

0x0006
Default lifetime for dynamic objects

0x0007
Default lifetime for image objects

0x0008
Default lifetime for static objects.

0x0009
Time (in seconds) between garbage collection.

0x000A
Maximum partition size (in MB).

0x000B
Maximum number of objects in a cache partition.

0x000C
Maximum size of the object in a cache partition.

0xFFFF
Operate on all policies.

Note: If the Command is a get (0x0001) this is the end of the subvector.

10-n
One of the following depending on the Policy Type above.

If the policy Type = 0x0001, 0x0002, 0x0003, 0x0004, or 0x0005:

10-11
Set value

  • 0x0001 (Enabled)

  • 0x0002 (disabled)

If the Policy Type = 0x0006, 0x0007, or 0x0008

10-13
The value representing the object lifetime in minutes.

The range is 0 to 10080, with 0 representing an object with no expiration.

If the Policy Type = 0x0009

10-13
The value representing the cache purge interval in minutes.

The range is 0 to 720, with 0 indicating that garbage collection should be disabled.

If the Policy Type =0x000A

10-11
A value representing the maximum partition size in MB. The range is 0-4095, with 0 indicating no limit.
Note:The value is not verified.

If the Policy = 0x000B

10-13
A value representing the maximum number of objects.

The range is 0-100000, with 0 indicating no limit.
Note:The value is not verified.

If the Policy = 0x000C

10-13
A value representing the maximum size of an object in the cache partition.

The range is 512 to 300000, entering a 0 indicates no limit.
Note:The value is not verified.

If the Policy = 0xFFFF

10-11
Cache transparent (Set Value)

  • 0x0001 (Enabled)

  • 0x0002 (Disabled)

12-13
HTTP Cache Control Header (Set Value)

  • 0x0001 (Enabled)

  • 0x0002 (Disabled)

14-15
Cache Dynamic (Set Value)

  • 0x0001 (Enabled)

  • 0x0002 (Disabled)

16-17
Cache Image (Set Value)

  • 0x0001 (Enabled)

  • 0x0002 (Disabled)

18-19
Cache Static (Set Value)

  • 0x0001 (Enabled)

  • 0x0002 (Disabled)

20-21
A value representing the maximum partition size in MB.

The range is 0 to 4095, with 0 indicating no limit.
Note:The value is not verified.

20-21
A value representing the maximum partition size in MB.

The range is 0 to 4095, with 0 indicating no limit.
Note:The value is not verified.

22-25
A value representing the maximum number of objects.

The range is 0 to 1000000, with 0 indicating no limit.
Note:The value is not verified.

26-29
A value representing the maximum size of an object in a cache partition.

The range is 512-3000000, specifying 0 indicates no limit.
Note:The value is not verified.

30-33
A value representing the dynamic object lifetime in minutes.

The range is 0 to 10080, with 0 representing an object with no expiration.
Note:The value is not verified.

34-37
A value representing the image object lifetime in minutes.

The range is 0 to 10080, specifying 0 indicates no limit.
Note:The value is not verified.

38-41
A value representing the static object lifetime in minutes.

The range is 0 to 10080, with 0 representing no limit.
Note:The value is not verified.

42-45
A value representing the cache purge interval in minutes.

The range is 0 to 720, with 0 indicating that garbage collection must be enabled.

Purge Command Subvector 

The Purge Command Subvector is used to clear all the objects from a cache partition.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0600

Query Command Subvector 

The Query Command Subvector is used to check if a given URL is in the cache partition.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0700

6-n
The URL Subfield

Statistics Command Subvector 

The Statics Command Subvector is used to get/reset the statistics for a cache partition.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0800

6-7
Command

URL Mask Command Subvector 

The URL Mask Command Subvector is used to list/modify the URL masks associated with a cache partition.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0900

6-7
Command

8-9
The URL Type

10-13
Lifetime

The range is 0-10080, with 0 representing an object with no expiration. Used only for Add (0x0002) command when URL type is Include (0x0001), Dynamic (0x0003), or Host On-Demand Client Cache applet (0x0004).

Note: If the Command is GET (0x0001) or Clear (0x0004) this is the end of the subvector.

14-n
One URL Command subvector.

Add Object Response Subvector 

The Add Object Response Subvector is used to respond to an Add (force) Object Command Subvector.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0101

6-9
Return Code

See "Return Codes".

Add (force) Response Subvector 

The Add (force) Response Subvector is used to respond to an Add (force) Object Command Subvector.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0111

6-9
Return Code

See "Return Codes".

Delete Object Response Subvector 

The Delete Object Response Subvector is used to respond to an Add (force) Object Command Subvector.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0401

6-9
Return Code

See "Return Codes".

Dependency Response Subvector 

The Dependency Response Subvector is used to respond to a Dependency Command Subvector.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0A01

6-9
Return Code

See "Return Codes".

10-n
Zero or more subfields.
Dependency Subfield
Note: This subfield must be before the URL Command Subfields that are for
the dependency. Required when have these Command-Dependency Type. For 
more information see Dependency Command Subvector.
 
Command      Dependency Type
 0x0001          0x0001          Note: Any URL Subfields following
                                       the Dependency Subfield are
                                       dependency URLs on that 
                                       dependency. 
 0x0001          0x0003
 
URL Subfield
Note: This subfield must be second when both subfields are required.  
         Required when have these Command-Dependency Type.
 
Command      Dependency Type
 0x0001          0x0001          Note: The Dependency Subfield prior 
                                       to the URL Subfield indicates 
                                       the URL for the dependency.  
 0x0001          0x0002

Disable Response Subvector 

The Disable Response Subvector is used to respond to the Disable Command Subvector.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0301

6-9
Return Code

See "Return Codes".

Enable Response Subvector 

The Enable Response Subvector is used to respond to the enable Command Subvector.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0201

6-9
Return Code

See "Return Codes".

Policy Response Subvector 

The Policy Response Subvector is used to respond to the Policy Command Subvector.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0501

6-9
Return Code

See "Return Codes".

If the Policy Command Subvector was PUT (0x0002) this is the end of the subvector.

10-n
One of the following depending on the Policy Type from the Policy Command Subvector.

If the policy Type = 0x0001, 0x0002, 0x0003, 0x0004, or 0x0005:

10-11
Set value

  • 0x0001 (Enabled)

  • 0x0002 (disabled)

If the Policy Type = 0x0006, 0x0007, or 0x0008

10-13
The value representing the object lifetime in minutes.

The range is 0 to 10080, with 0 representing an object with no expiration.

If the Policy Type = 0x0009

10-13
The value representing the cache purge interval in minutes.

The range is 0 to 720, with 0 indicating that garbage collection should be disabled.

If the Policy Type =0x000A

10-11
A value representing the maximum partition size in MB. The range is 0-4095, with 0 indicating no limit.
Note:The value is not verified.

If the Policy = 0x000B

10-13
A value representing the maximum number of objects.

The range is 0-100000, with 0 indicating no limit.
Note:The value is not verified.

If the Policy = 0x000C

10-13
A value representing the maximum size of an object in the cache partition.

The range is 512 to 300000, entering a 0 indicates no limit.
Note:The value is not verified.

If the Policy = 0xFFFF

10-11
Cache transparent (Set Value)

  • 0x0001 (Enabled)

  • 0x0002 (Disabled)

12-13
HTTP Cache Control Header (Set Value)

  • 0x0001 (Enabled)

  • 0x0002 (Disabled)

14-15
Cache Dynamic (Set Value)

  • 0x0001 (Enabled)

  • 0x0002 (Disabled)

16-17
Cache Image (Set Value)

  • 0x0001 (Enabled)

  • 0x0002 (Disabled)

18-19
Cache Static (Set Value)

  • 0x0001 (Enabled)

  • 0x0002 (Disabled)

20-21
A value representing the maximum partition size in MB.

The range is 0 to 4095, with 0 indicating no limit.
Note:The value is not verified.

22-25
A value representing the maximum number of objects.

The range is 0 to 1000000, with 0 indicating no limit.
Note:The value is not verified.

26-29
A value representing the maximum size of an object in a cache partition.

The range is 512-3000000, specifying 0 indicates no limit.
Note:The value is not verified.

30-33
A value representing the dynamic object lifetime in minutes.

The range is 0 to 10080, with 0 representing an object with no expiration.
Note:The value is not verified.

34-37
A value representing the image object lifetime in minutes.

The range is 0 to 10080, specifying 0 indicates no limit.
Note:The value is not verified.

38-41
A value representing the static object lifetime in minutes.

The range is 0 to 10080, with 0 representing no limit.
Note:The value is not verified.

42-45
A value representing the cache purge interval in minutes.

The range is 0 to 720, with 0 indicating that garbage collection must be disabled.

Purge Response Subvertor 

The Purge Response Subverted is used to respond to a Purge Command Subverted.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0601

6-9
See "Return Codes".

Query Response Subvector 

The Query Response Subvector is used to check if a given URL is in the cache partition.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0701

6-9
Return Code

See "Return Codes".

Note: If the return code is bad (not 0x00000000), this is the end of the response.

10-37
The time the object was last modified in the GMT.
Note:This field will not exist if the return code was not 0x00000000 or if it is not known by the Cache Partition.

10-13
Seconds

14-17
Minutes

18-21
Hours

22-25
Months since Jan. (0-11)

26-29
Years from 1900

30-33
Days since Sunday (0-6)

34-37
Day of the month

Statistics Response Subvector  The Statistics Response Subvector responds to the Statistics Command Subvector.

0-3
Length

The entire length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0801

6-9
Return Code

This is the return code for the subvector.

10-

10-13
The current number of bytes in the Cache Partition. The number only reflects the entity bytes, and does not include the bytes used to store the headers or control block usage.

14-17
The high water mark for the number of bytes in the Cache Partition.

18-21
The current number of objects in the Cache Partition.

22-25
The high water mark for the number of objects in the Cache Partition.

26-29
The total of times that objects were found in the Cache Partition.

30-33
The total of times that objects were not found in the Cache Partition.

34-37
The number of objects added to the Cache Partition explicitly by Include URL mask.

40-43
The number of objects not added to the Cache Partition because caching was turned off.

44-47
The number of objects not added to the cache partition because the object is too big.

48-51
The number of objects not added to the Cache Partition because DONT CACHE is specified in the HTTP control header.

52-55
The number of object not added to the Cache Partition because explicitly excluded by the URL mask.

56-59
The number of objects not added to the Cache Partition because the object was stale.

60-63
The number of objects not added to the Cache Partition because the image object explicitly not cached.

64-67
The number of objects not added to the Cache Partition because the static object explicitly not cached.

68-71
The number of objects not added to the Cache Partition because the dynamic object was not explicitly cached.

72-75
The number of objects purged due to a full cache or all the cache partitions exceed the total amount allowed by the Web Server Cache.

76-79
The number of objects purged due to the expiration of the objects lifetime.

80-83
The number of objects explicitly purged, either by giving the URL or purging the entire partition.

84-87
The number of objects purged due to the invalidation of the dependency.

URL Mask Response Subvector 

The URL Mask Response Subvector is used to respond to a URL Mask Command Subvector.

0-3
Length

The length (in bytes) of the vector, including the length and key fields, as well as any subvectors.

4-5
Key

0x0901

6-9
Return Code

This is the return code for the subvector. See "Return Codes".

10-n
Zero or more URL Subvectors if the URL Mask Command Subvector was GET (0x0001).

Subfield Formats

This section describes the field descriptions for the subfields.

Figure 19. Subfield Format

Subfield Format

Length: The unsigned 32-bit value representing the length (in bytes) of the entire subfield, including the length and key fields. The acceptable range is 6-4GB.

Key: The unsigned 16-bit value representing the subfield key. The command subfield keys include:

The response subfield keys are:

Dependency Subfield 

The Dependency Subfield for the URL Mask Response Subvector.

0-3
Length

The length (in bytes) of the vector, including the length and key fields.

4-5
Key

0x0050 - request

0x0051 - response

6-n
Dependency

Must be 1 to 50 in length.

Name Subfield 

The Name Subfield for the URL Mask Response Subvector.

0-3
Length

The length (in bytes) of the vector, including the length and key fields.

4-5
Key

0x00030 - request

6-n
Name

Must be 1 to 8 in length.

Object Subfield 

The Object Subfield for the URL Mask Response Subvector.

0-3
Length

The length (in bytes) of the vector, including the length and key fields.

4-5
Key

0x002 - request

6-n
Object

The object must be formatted like a HTTP Response. It is an array of characters.

Password Request Subfield 

The Password Request Subfield for the URL Mask Response Subvector.

0-3
Length

The length (in bytes) of the vector, including the length and key fields.

4-5
Key

0x0400

6-14
The seed used in encryption (must be 8 bytes).

15-n
Password

Must be 1 to 8 bytes in length and be encrypted.

URL Request Subfield 

The URL Request Subfield for the URL Mask Response.

0-3
Length

The length (in bytes) of the vector, including the length and key fields.

4-5
Key

0x0010 - request

0x0011 - response

6-n
URL or URL Mask

This is an array of characters, the array must be 1 to 255 in length.

Return Codes

It is important to check the return codes for each response subvector in addition to the return code in the response vector. The return code for the response vector will be set to a non-zero value if a severe error was detected, in which case all the command subvectors from the command vector might or might not have a corresponding response subvector.

Return Codes and Descriptions 
0000 0000: Operation was successful
0001 0000: Object not found
0002 0000: Cache partition is already enabled
0003 0000: Cache partition is already disabled.
0004 0000: Cache partition is not enabled
0005 0000: Cache partition is not defined
0006 0000: Cache partition is terminating
0007 0000: URL subfield is required but not present
0008 0000: Purge interval provided is not valid
0009 0000: Unsupported Set value
000A 0000: Unsupported Command value
000B 0000: Unsupported Policy type value
000C 0000: Unsupported URL type value
000D 0000: Unsupported vector key
000E 0000: Unsupported subvector key
000F 0000: Unable to parse object's headers
0010 0000: Unable to obtain storage
0011 0000: Object too large to add to partition
0012 0000: Vector format is not valid
0013 0000: Object is not cacheable
0014 0000: HTTP parse error detected
0015 0000: Object subfield is required but not present
0016 0000: Dependency subfield is not provided or invalid
0017 0000: Authentication Vector required
0018 0000: Authentication Vector not required - therefore ignored
0019 0000: Dependency was not in Dependency table
001A 0000: Dependency URL was not in Dependency table
001B 0000: Unsupported Depend type
001C 0000: Bad userid/password/permission for ECC
001D 0000: Bad URL mask type for the image load on the box
FF01 yyyy: Command failed. Last 2 bytes contain additional information.
0101: Object was not found.
0102: Object cannot be cached.
0103: Object already exists in partition.
0104: Partition initialization failed, maximum number of partitions already active.
0105: Partition is active.
0106: Partition is not active.
0107: The partition is in a pending state and cannot execute the command. Wait a
few seconds and try the command again.
0108: Partition is not defined.
0109: URL type is not supported.
010A: URL pointer is not valid.
010B: Partition number is not valid.
010C: Partition command is not supported.
010D: Partition pointer is not valid.
010E: Partition handle does not reference an active partition.
010F: Partition handle does not reference a valid partition.
0110: Policy pointer is required but not present.
0111: Statistics pointer is required but not present.
0112: Purge interval is too large.
0113: Dependency already has URL on it.
0FFF: External cache control is not available.
FFF9: Unable to acquire storage.
FFFA: Unable to acquire a partition handle.
FFFB: Policy SRAM pointer is required but not present.
FFFC: Partition SRAM pointer is required but not present.
FFFD: Unable to allocate/initialize cache expiration interval.
FFFE: Unable to allocate/initialize cache partition.
FFFF: Unable to allocate/initialize cache core.



[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]